home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 351-375 / disk_354 / keymacro / keymacro.doc < prev    next >
Text File  |  1992-05-06  |  11KB  |  242 lines
  1. ======================================================================
  2. =========================== KeyMacro v1.4 ============================
  3. ================== * A macro key handler utility * ===================
  4. ======================================================================
  5.  
  6. ============================= IMPORTANT ==============================
  7. ======================================================================
  8. The  current release of KeyMacro requires arp.library, mxm.library and
  9. Null-Handler  to  be  present  in your system.  Put the libraries into
  10. LIBS:   and  the  handlers  into  L:.  Then add the following lines to
  11. DEVS:MountList:
  12.  
  13.     NULL:    Handler        = L:Null-Handler
  14.         Stacksize    = 500
  15.         Priority    = 5
  16.         GlobVec        = -1
  17.     #
  18.  
  19. You  _M_U_S_T_  install  the Null-Handler using the CLI command 'Mount
  20. NULL:' before starting KeyMacro or the KeyMacro handler won't budge.
  21.  
  22. Secondly  there's  another  pitfall to overcome:  I don't know anybody
  23. else  who has the Aztec 5.0 compiler update yet.  And thirdly:  I only
  24. know  one  Arp  wrapper package which is compatible with the Aztec 5.0
  25. release:  my wrapper.
  26.     If  you find a working wrapper for Lattice 'C' it may turn out
  27. quite easy to 're-port' the code.
  28.  
  29. ============================ BACKGROUND ==============================
  30. ======================================================================
  31. Some  time  ago  I  played around with a keymap editor to customize my
  32. keymap  settings.  But there was a feature I missed:  there wasn't any
  33. hot-key  support  (just  like  PopCLI  or  DMouse).  I also discovered
  34. another  disadvantage:   to change the keymap settings you had to load
  35. the  keymap  editor, edit the map, save it to disk and then install it
  36. via  SetMap  -  and even that didn't guarantee that the new keymap was
  37. accepted:   do  you  remember that SetMap does not load new keymaps if
  38. the  name matches a keymap already in memory?  Furthermore keymap keys
  39. may only generate string sequences of up to 32 characters.  With these
  40. topics in mind I decided to write my own keyboard macro handler.
  41.  
  42. ============================= FEATURES ===============================
  43. ======================================================================
  44. KeyMacro  provides  an  easy  way to manage keyboard macros (character
  45. sequences)  and  hot-key program execution.  You edit a script file in
  46. which  all  required key combinations are defined and call KeyMacro to
  47. update the macro list - that's all.  You can map up to eight functions
  48. to  each  key, including keys such as the cursor keys, the return key,
  49. etc.   The hot-key programs will use an AmigaDOS search path list when
  50. getting  executed.  Each macro key call gets processed asynchronously,
  51. i.e.   invoking  one  hot-key  command  after the other will start all
  52. commands, nothing will be skipped.
  53.  
  54. =========================== INSTALLATION =============================
  55. ======================================================================
  56. Place   KeyMacro-Handler   in   L:,   KeyMacro   in   C:    or   SYS:,
  57. electronic.library  in  LIBS:,  copy your KeyMacro.config to S:.  Type
  58. "KeyMacro"  to  install/update  macro keys, "KeyMacro quit" to remove.
  59. Note:   if  the  installation fails the main process ("KeyMacro") will
  60. wait  for  a  handshake  signal  which may never arrive.  In this case
  61. pressing  CTRL-C  will  stop  the main process.  It will shut down and
  62. issue an error message.
  63.  
  64. =============================== USAGE ================================
  65. ======================================================================
  66. KeyMacro is controlled via a script file.  Here is a sample:
  67.  
  68.     ; KeyMacro v1.0 configuration file.
  69.     ; The semicolon says that this is a comment:
  70.  
  71.     ; Some keyboard macros.
  72.  
  73.     key ctrl+esc = "EndCLI > NIL:\n"
  74.     key lalt+0 = "CD DF0:\n"
  75.     key lalt+1 = "CD DF1:\n"
  76.  
  77.     ; A hot-key command definition
  78.  
  79.     command lalt+v = "C:vt100 +i s:vt100.init" window "VT100"
  80.  
  81. Each  definition  must  be  "key"  or "command".  "Key" means that the
  82. following  definition  will be a sequence of characters to be inserted
  83. into  the input stream.  "Command" means that the following definition
  84. will be the name and the arguments of a program to be executed.
  85.     The  macro  type  is  followed  by  the  key combination to be
  86. pressed to execute the macro definition.  This combination consists of
  87. the keyboard qualifier and the key.  An unlimited number of qualifiers
  88. are allowed.  KeyMacro knows the following qualifiers:
  89.  
  90.     NONE ..........    No qualifier (note: a qualifier MUST be given!)    
  91.     CTRL ..........    The control key
  92.     NUMPAD ........    The numeric pad
  93.     LSHIFT ........    The left shift key
  94.     RSHIFT ........    The right shift key
  95.     LALT ..........    The left alternate key
  96.     RALT ..........    The right alternate key
  97.     LAMIGA ........    The left Amiga key (Commodore key)
  98.     RAMIGA ........    The right Amiga key
  99.  
  100. A qualifier must be given or the macro parser will panic; if you don't
  101. need a qualifier simply enter NONE as the qualifier.
  102.     The  qualifier  is  followed  by  the  key to attach the macro
  103. expression  to.   This  can  be  any  key  on  the keyboard, including
  104. function keys, cursor keys, etc.  If there is no ASCII value available
  105. for the key, you can take a name from the following list:
  106.  
  107.     TAB ...........    The tabulator key
  108.     ESC ...........    The escape key
  109.     SPACE .........    The space key
  110.     RETURN ........    The return key
  111.     ENTER .........    The enter key (numeric pad)
  112.     DEL ...........    The delete key
  113.     BACKSPACE .....    The backspace key
  114.     HELP ..........    The help key
  115.  
  116.     LEFT ..........    The cursor-left key
  117.     RIGHT .........    The cursor-right key
  118.     UP ............    The cursor-up key
  119.     DOWN ..........    The cursor-down key
  120.  
  121.     F1 ............    The function key #1
  122.     F2 ............    The function key #2
  123.     F3 ............    The function key #3
  124.     F4 ............    The function key #4
  125.     F5 ............    The function key #5
  126.     F6 ............    The function key #6
  127.     F7 ............    The function key #7
  128.     F8 ............    The function key #8
  129.     F9 ............    The function key #9
  130.     F10 ...........    The function key #10
  131.  
  132. These  equivalents  can  be  used just like characters.  Note:  if you
  133. enter more than one single character as the command key only the first
  134. character will be taken (except for the key names listed above).
  135.     The key is followed by a '=' sign, this tells the macro parser
  136. to remember the following string as the macro string to be
  137. entered/executed. This string must be enclosed in quotes or the parser
  138. will take only the first word of it. Inside this string sequences of
  139. two characters can be used to generate key codes not supported by the
  140. ASCII keyboard. These sequences are:
  141.  
  142.     \u ............    Cursor-up key
  143.     \d ............    Cursor-down key
  144.     \l ............    Cursor-left key
  145.     \r ............    Cursor-right key
  146.  
  147.     \n ............    The return key
  148.  
  149.     \h ............    The help key
  150.     \b ............    The backspace key
  151.     \e ............    The delete key (sorry, \d was already used)
  152.     \f1 - \f10 ....    The function keys
  153.     \" ............    A quote
  154.     \\ ............    The escape symbol ('\')
  155.  
  156. A  hot-key  command  definition can be followed by a "window" keyword.
  157. This  keyword  identifies  the next string (enclosed in quotes) as the
  158. typical window title of the command to be loaded.  Before this command
  159. is  executed  each open window is checked for this title.  If a window
  160. title matches the name it is brought to the front, no new command will
  161. be loaded.
  162.  
  163.                                   *
  164.  
  165.            KeyMacro has the following command-line options:
  166.  
  167. STARTUP .......    Followed by the name of the file to be used as
  168.         configuration file will keep KeyMacro from looking
  169.         for S:KeyMacro.config as the standard configuration
  170.         file.
  171.  
  172. QUIT ..........    Removes KeyMacro from memory.
  173.  
  174. INFO ..........    Gives a brief information on the program.
  175.  
  176. ============================== CREDITS ===============================
  177. ======================================================================
  178. Credits  go  to ARP Programmers for the most recent version of ARP and
  179. to Matt Dillon for DMouse.
  180.     A special mention must also go to Bill Hawes, author of ARexx,
  181. and  to the authors of CygnusEd Pro 2 (Bruce Dawson & Colin Fox) whose
  182. programs both controlled the compiler runs.
  183.  
  184. ================== COPY FEE, AUTHORS REQUEST, ETC. ===================
  185. ======================================================================
  186. This  is the first time I release a program as shareware.  Consider it
  187. as  a  "test balloon" for coming projects.  A small contribution of at
  188. least $5 or at least DM 10,- will insure your registration, giving you
  189. the  opportunity  to  receive updates, new programs from MXM and more.
  190. Think  about  it, if you like this program and use it often this small
  191. amount of money will support the author and encourage him to start new
  192. projects.
  193.  
  194.        Send comments, bug reports, ideas and contributions to:
  195.  
  196.                           Olaf Barthel, MXM
  197.                           Brabeckstrasse 35
  198.                           D-3000 Hannover 71
  199.  
  200.                      Federal Republic of Germany
  201.  
  202. Permission  hereby  granted  to  re-distribute  KeyMacro  v1.4  in its
  203. entirety for non profit usage only.
  204.  
  205. ============ REVISION HISTORY (most recent change first) =============
  206. ======================================================================
  207. V1.4    Wow!   It  works!   The reasons for the constant failures were
  208.     located  in  1) mxm.library, 2) in the Arp wrapper for Lattice
  209.     'C',   3)   in   KeyMacro   itself   and   4)   of  course  in
  210.     KeyMacro-Handler.   Needless to say, mxm.library was fixed and
  211.     the code has once more changed the compiler - KeyMacro 1.4 now
  212.     compiles   under   Aztec   5.0.    Programs   started  by  the
  213.     executor-process will no longer block until the program exits.
  214.     This  is  now  probably  the only input.device example program
  215.     written  in  Aztec  'C'  which doesn't use ANY inline assembly
  216.     language code (#asm/#endasm).
  217.  
  218. V1.3    Well, I wouldn't shoot  my  grandma  to get it working, but it
  219.     really  starts  to  become  a  nuisance:  1.2 still wasn't the
  220.     success  I  had  expected.  I took a second look into RKM Exec
  221.     and  discovered  that  interrupt handlers be located in public
  222.     ram.   As  a  result  almost all static data declarations have
  223.     been replaced by memory allocations.
  224.  
  225. V1.2    I  guess  you know what happened:  it still didn't work right.
  226.     The  code  is  now  much  more compact and has been recompiled
  227.     using Lattice 'C' 5.04.
  228.  
  229. V1.1    KeyMacro  obviously  worked  on  only  one machine:  my Amiga.
  230.     This  is the first attempt to fix it.  I cleaned up the code I
  231.     didn't  think  to  be that much important which hopefully will
  232.     fix the problem.
  233.  
  234. V1.0    First  public  release;  seems  that  it  works (what did I do
  235.     wrong?).
  236.  
  237.                                   *
  238.  
  239.              Do only its possibilities make it an Amiga?
  240.  
  241.                         WHERE IS THE MAGIC ???
  242.